Skip to content

Update Arduino IDE 2.x debugger tutorials for compatibility with versions >=2.3.0 #1792

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 6, 2024

Conversation

per1234
Copy link
Contributor

@per1234 per1234 commented Mar 3, 2024

Background

A major reworking of the debugger configuration system was released in Arduino IDE 2.3.0 (arduino/arduino-ide#2281). This caused several breaking changes to the Arduino IDE user interface which rendered debugger tutorials outdated:

Tools > Programmer Menu Selection Required

The IDE is now configured for the debug probe hardware in use via the Tools > Programmer menu selection.

As a side effect of that change, it is now mandatory for the user to make the appropriate selection from that menu in order to use the debugger. If no selection is made, the IDE disables the "Start Debugging" button. For this reason, it will be important for the debugger tutorials to include this.

Arduino IDE versions prior to 2.3.0 did not use the "Programmer" selection for configuration of the debugger. Although selecting a programmer before starting the debugger is not mandatory for users of older versions of the IDE, it also will not cause any harm and that menu was present in those versions of the IDE as well. So the inclusion of a Programmer menu selection step in the tutorials does not break their compatibility with previous versions of Arduino IDE 2.x.

Change to debug_custom.json Format

There was a breaking change to the data structure of the debug_custom.json file that allows the user to adjust the debugger configuration.

The tutorial for using the IDE 2.x debugger with a J-Link debug probe requires the use of the debug_custom.json feature. The change to the file's data structure rendered that part of the tutorial outdated.

Bug in debug_custom.json Feature

A regression was introduced in Arduino IDE 2.3.0 that causes the configuration defined in certain fields of debug_custom.json to no longer have an effect (arduino/vscode-arduino-tools#48), causing the J-Link tutorial to no longer be usable.

A fix for the IDE bug is now in progress (arduino/vscode-arduino-tools#49), but it will likely be some time before this can be shipped in a new Arduino IDE release.

What This PR Changes

  • Add instructions for configuring debug probe via Tools > Programmer menu.
  • Update J-Link tutorial for new debug_custom.json format.
  • Add alternative fields to J-Link debug_custom.json to work around tutorial-breaking IDE bug.

Contribution Guidelines

@per1234 per1234 added bug Something isn't working arduino Bugs and fixes added by the Arduino Team labels Mar 3, 2024
Copy link

vercel bot commented Mar 3, 2024

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name Status Preview Updated (UTC)
docs-content ❌ Failed (Inspect) Mar 5, 2024 5:53pm

per1234 added 3 commits March 5, 2024 07:54
…IDE 2.x debugger tutorials

A major reworking of the debugger configuration system was released in Arduino IDE 2.3.0. One of the user facing changes
is the ability to configure the IDE for the debug probe hardware in use via the "Tools > Programmer" menu selection.

As a side effect of that change, it is now mandatory for the user to make the appropriate selection from that menu in
order to use the debugger. If no selection is made, the IDE disables the "Start Debugging" button. For this reason, it
will be important for the debugger tutorials to include this.

Arduino IDE versions prior to 2.3.0 did not use the "Programmer" selection for configuration of the debugger. Although
selecting a programmer before starting the debugger is not mandatory for users of older versions of the IDE, it also
will not cause any harm and that menu was present in those versions of the IDE as well. So the inclusion of a
"Programmer" menu selection step in the tutorials does not break their compatibility with previous versions of Arduino
IDE 2.x.
A major reworking of the Arduino IDE 2.x debugger configuration system was released in Arduino IDE 2.3.0. This included
a breaking change to the data structure of the debug_custom.json file that allows the user to adjust the debugger
configuration.

The tutorial for using the Arduino IDE 2.x debugger with a J-Link debug probe requires the use of the debug_custom.json
feature. The change to the file's data structure rendered that part of the tutorial outdated. It is hereby updated to
use the new data structure.

Including instructions for the different debug_custom.json structure that would be required for users of versions of
Arduino IDE 2.x older than 2.3.0 would have added significant complexity to an already dense tutorial, making it
significantly less approachable to the reader and prone to misinterpretation. For this reason, the decision was made to
specify a requirement of Arduino IDE 2.3.0 as the minimum for the tutorial.
…rial breaking IDE bug

The tutorial for using the Arduino IDE 2.x debugger with a J-Link debug probe requires the use of a debug_custom.json
file to adjust the debugger configuration in order to allow it to be used with the J-Link.

A regression was introduced in Arduino IDE 2.3.0 that causes the configuration defined in certain fields of
debug_custom.json to no longer have an effect, causing the tutorial to no longer be usable.

A fix for the bug is now in progress, but it will likely be some time before this can be shipped in a new Arduino IDE
release. For this reason, it will be worth adjusting the contents of the debug_custom.json file provided in the tutorial
to work around the bug, allowing it to work with the current versions of Arduino IDE.

Once a new release of Arduino IDE is made with the bug fixed, this commit should be reverted and the minimum IDE version
specified in the tutorial bumped. However the workaround is applied in a manner that will not cause any harm even when
present in the debug_custom.json file while a fixed version of Arduino IDE is in use.
@per1234 per1234 force-pushed the update-debug_custom branch from a8b105d to e9ebf1b Compare March 5, 2024 15:56
@per1234 per1234 merged commit e59e6ee into main Mar 6, 2024
@per1234 per1234 deleted the update-debug_custom branch March 6, 2024 11:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
arduino Bugs and fixes added by the Arduino Team bug Something isn't working
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants